import { Callout } from "nextra-theme-docs";

# Configuration of appsettings.json

`appsettings.json` is the core configuration file of GZCTF, which is configured by mounting into the container. This document will introduce the meaning of each field in the configuration file.

<Callout type="info">

You need to restart the GZCTF service every time you update `appsettings.json` to make it effective.

</Callout>

## Structure of the configuration file

Here is a complete example of configuration:

```json
{
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Database": "Host=db:5432;Database=gzctf;Username=postgres;Password=<Database Password>"
    // redis is optional
    //"RedisCache": "cache:6379,password=<Redis Password>"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "Loki": {
      "Enable": true,
      "EndpointUri": "http://loki:3100",
      "Labels": [
        {
          "Key": "app",
          "Value": "gzctf"
        }
      ],
      "PropertiesAsLabels": ["app"],
      "Credentials": {
        "Login": "login",
        "Password": "password"
      },
      "Tenant": "my-tenant",
      "MinimumLevel": "Trace"
    }
  },
  "Telemetry": {
    "Prometheus": {
      "Enable": false,
      "Port": 3000,
      "TotalNameSuffixForCounters": false
    },
    "OpenTelemetry": {
      "Enable": false,
      "Protocol": "Grpc",
      "EndpointUri": "http://jaeger-collector:4317"
    },
    "AzureMonitor": {
      "Enable": false,
      "ConnectionString": "InstrumentationKey=12345678-abcd-abcd-abcd-12345678..."
    },
    "Console": {
      "Enable": false
    }
  },
  "EmailConfig": {
    "SenderAddress": "",
    "SenderName": "",
    "UserName": "",
    "Password": "",
    "Smtp": {
      "Host": "localhost",
      "Port": 587,
      "BypassCertVerify": false
    }
  },
  "XorKey": "<Random Key Str>",
  "ContainerProvider": {
    "Type": "Docker", // or "Kubernetes"
    "PortMappingType": "Default",
    "EnableTrafficCapture": false,
    "PublicEntry": "ctf.example.com", // or "xxx.xxx.xxx.xxx"
    "DockerConfig": {
      // optional
      "SwarmMode": false,
      "ChallengeNetwork": "",
      "Uri": "unix:///var/run/docker.sock",
      "UserName": "",
      "Password": ""
    },
    "KubernetesConfig": {
      // optional
      "Namespace": "gzctf-challenges",
      "ConfigPath": "kube-config.yaml",
      "AllowCIDR": [
        // allow the cluster CIDR for LB
        "10.0.0.0/8"
      ],
      "DNS": [
        // custom DNS to avoid cluster DNS
        "8.8.8.8",
        "223.5.5.5"
      ]
    }
  },
  "RequestLogging": false,
  "DisableRateLimit": false,
  "RegistryConfig": {
    "UserName": "",
    "Password": "",
    "ServerAddress": ""
  },
  "CaptchaConfig": {
    "Provider": "None",
    "SiteKey": "...",
    "SecretKey": "...",
    "GoogleRecaptcha": {
      "VerifyAPIAddress": "https://www.recaptcha.net/recaptcha/api/siteverify",
      "RecaptchaThreshold": "0.5"
    }
  },
  "ForwardedOptions": {
    "ForwardedHeaders": 5, // a flag enum, see following link
    "ForwardLimit": 1,
    "ForwardedForHeaderName": "X-Forwarded-For",
    // use the following options to allow proxy
    "TrustedNetworks": ["10.0.0.0/8"],
    "TrustedProxies": ["10.0.0.1"]
  },
  "Kestrel": {
    "Endpoints": {
      "Web": {
        "Url": "http://*:8080"
      },
      "Prometheus": {
        "Url": "http://*:3000"
      }
    },
    "Limits": {
      "MaxResponseBufferSize": 2048,
      "MaxRequestBufferSize": 1048576,
      "MaxRequestLineSize": 8192,
      "MaxRequestHeadersTotalSize": 32768,
      "MaxRequestHeaderCount": 100,
      "MaxRequestBodySize": 27262946,
      "KeepAliveTimeout": "0.0:5:0",
      "RequestHeadersTimeout": "0.0:5:0",
      "MaxConcurrentConnections": null,
      "MaxConcurrentUpgradedConnections": null
    },
    "AddServerHeader": true,
    "AllowResponseHeaderCompression": true,
    "AllowSynchronousIO": false,
    "AllowAlternateSchemes": false,
    "DisableStringReuse": false,
    "ConfigurationLoader": null
  }
}
```

## Core configuration fields

### ConnectionStrings

Here we can the configure the connection of the database. `Database` is required, and `RedisCache` is optional.

GZCTF uses PostgreSQL as the backend database and data persistence, and Redis as the cache and message queue. In the case of single instance deployment, Redis is not necessary, and GZCTF's memory cache can be used directly; in the case of multi-instance deployment, Redis is necessary as a shared cache and SignalR's Scale-Out broadcast.

<Callout type="info">

GZCTF only supports PostgreSQL as the database, and does not support MySQL and other databases. Please fill in the correct database connection settings in the configuration file.

</Callout>

### Logging

You can configure the logging level and scopes, besides, GZCTF also supports sending logs to Loki server.

- **LogLevel**: The minimal logging level per namespace.
- **Loki**: The configuration of Loki server.

  - **Enable**: Enable it or not.
  - **EndpointUri**: The URI of Loki server.
  - **Labels**: Optional. The global log event labels.
  - **PropertiesAsLabels**: Optional. The list of properties, which should be mapped to Loki labels.
  - **Credentials**: Optional. Credentials, which will be used for basic auth
  - **Tenant**: Optional. The Tenant ID used for sending logs to Loki server.
  - **MinimumLevel**: Optional. Minimal logging level.

Available logging levels: Trace, Debug, Information, Warning, Error, Critical, None.

### Telemetry

GZCTF supports metrics and distributed tracing. You can configure the providers you want to use.

- **Prometheus**: Prometheus endpoint support.

  - **Enable**: Enable it or not.
  - **Port**: Optional. Set the port that Prometheus `/metrics` endpoint listens on. If this is configured, additional manual configuration of `Kestrel.Endpoints` is required to make the server listen to the specified port normally.
  - **TotalNameSuffixForCounters**: Optional. Whether to include `_total` suffix in counters or not.

- **OpenTelemetry**: Exporting metrics and tracing data to OpenTelemetry.

  - **Enable**: Enable it or not.
  - **Protocol**: `Grpc` or `HttpProtobuf`.
  - **EndpointUri**: The OpenTelemetry endpoint URI to push telemetry data.

- **AzureMonitor**: Exporting metrics and tracing data to ApplicationInsights.

  - **Enable**: Enable it or not.
  - **ConnectionString**: The connection string.

- **Console**: Exporting tracing data to console.

  - **Enable**: Enable it or not.

### EmailConfig

Here we can configure the information of email sending server. If you use email registration and other email features, this is required.

- **SenderAddress:** Email address of the sender
- **SenderName:** Name of the sender
- **UserName:** SMTP Server username
- **Password:** SMTP Server password
- **Smtp:** SMTP Server address and port
- **BypassCertVerify:** Whether to bypass the certificate verification of the SMTP server

<Callout type="info">

Some cloud service provider may block port 465, please try port 587.

</Callout>

### XorKey

Here we can configure the encryption key for encrypting the private key of the competition in the database. It can string of any length.

### ContainerProvider

Heer we can configure the container backend which is required for creating containers dynamically during the game.

- **Type:** Type of the container backend: `Docker` or `Kubernetes`。
- **PublicEntry:** Public entry of the container backend, used to generate the address of the competition, and show to the participating teams.
- **PortMappingType:** Port mapping type, can be `Default` or `PlatformProxy`。
- **EnableTrafficCapture:** Enable/Disable traffic capture, only available when `PortMappingType` is configured as `PlatformProxy`. Captured traffic will be saved to `/app/files/capture`.

#### Docker

- **SwarmMode:** Use Swarm mode, GZCTF will use Swarm API to manage the containers if this is enabled.

  <Callout type="warning">

  Since Docker Swarm is no longer an active project, security features are far behind k8s, and it is not recommended.

  </Callout>

- **Uri:** Docker API Server Address

  - If you use local docker, please leave Uri empty, and mount `/var/run/docker.sock` into the container.
  - If you use external docker, please set Uri to the corresponding docker API Server, **external API authentication has not been implemented, this deployment method is not recommended**

- **ChallengeNetwork:** Specify the network where the challenge container is located. If not specified, the default network will be used.

- **UserName, Password:** Docker API Basic Auth username and password, optional.

#### Kubernetes

- **Namespace:** Kubernetes namespace, used to create the namespace of the challenge instance, the default is `gzctf-challenges`
- **ConfigPath:** Kubernetes configuration file path, used to connect to the cluster, default value is `kube-config.yaml`
- **AllowCIDR:** White list of CIDR that can access the Pod
- **DNS:** custom DNS server list

To use the default behavior, please put the cluster connection configuration into the `kube-config.yaml` file and mount it to the `/app` directory. Do not change it if you don't understand the behavior of the experimental function.

<Callout type="info">

Please note that you need to change the `server` field in the `kube-config.yaml` file to point to the API Server address of the cluster. The default address of the cluster is generally `https://127.0.0.1:6443`, which needs to be changed to the actual address of the cluster.

</Callout>

<Callout type="info" emoji="👾">

In order to meet the network policy, GZCTF will create a NetworkPolicy named `gzctf-policy` in the Namespace of the challenge to restrict access. GZCTF will automatically detect whether this NetworkPolicy already exists. If it exists, it will not be created again, so you can customize the network policy by creating or editing this NetworkPolicy.

</Callout>

### RequestLogging

Enable/Disable request logging, if enabled, detailed information of each request will be appended to the log. Static file requests are not included in the output here.

### DisableRateLimit

Enable/Disable request rate limit, if enabled, the request rate of each IP and API will be limited according to the preset rules.

### RegistryConfig

Here we can configure the username and password of the Docker Registry, which is used to pull the container image for dynamic container during the game.

- **UserName:** User name of the Docker Registry
- **Password:** Password of the Docker Registry
- **ServerAddress:** Address of the Docker Registry, please note that the `https://` prefix is not required

<Callout type="info">

Please make sure that the password does not contain special characters (such as `":@` etc., but `_` can be used), otherwise it may cause template injection problems and make `Secret` not work properly.

</Callout>

### CaptchaConfig

Configure the Captcha used for user registration, account recovery and login, optional.

- **Provider:** Captcha provider, can be `None`, `GoogleRecaptcha` or `CloudflareTurnstile`
- **SiteKey:** Captcha Sitekey
- **SecretKey:** Captcha Secretkey

#### GoogleRecaptcha

Configure the Google Recaptcha v3 related information, optional.

- **VerifyAPIAddress:** Google Recaptcha verify API address
- **RecaptchaThreshold:** Google Recaptcha threshold, used to determine whether the captcha is effective

### ForwardedOptions

Here we can configure the reverse proxy, which is used to get the real IP address, optional.

- **ForwardedHeaders:** Enum for ForwardedHeaders in reverse proxy, please use `5` as the default value. For more details, see [ForwardedHeaders Enum](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.httpoverrides.forwardedheaders)
- **ForwardLimit:** Limit the number of proxy hops allowed, the default is `1`
- **ForwardedForHeaderName:** The name of the reverse proxy IP address header
- **TrustedNetworks:** List of trusted networks for reverse proxy, represented by CIDR.
- **TrustedProxies:** List of trusted proxies for reverse proxy, represented by IP addresses or domain names.

<Callout type="info">

If you want to ignore the trust list of reverse proxies and allow any IP address to access, please refer to the solution for forwarding Linux and non-IIS reverse proxies, and set the environment variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED` to `true`.

</Callout>

For other fields, please refer to the official documentation: [Configure ASP.NET Core to work with proxy servers and load balancers](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer) and [ForwardedHeadersOptions class](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions)

### Kestrel

Kestrel is the built-in web server used by GZCTF. With this configuration, you can control the behavior of Kestrel, such as specifying the HTTP protocol, modifying the request size limit, and more.

- **Endpoints**: Configure the URL that the web server listens on.
- For other configurable fields, please refer to the properties of the `KestrelServerOptions` class in the official documentation: [KestrelServerOptions class](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions)
